<!DOCTYPE HTML>
<html lang="en">
<head>
<title>#MenuMaskKey - Syntax &amp; Usage | AutoHotkey</title>
<meta name="description" content="The #MenuMaskKey directive changes which key is used to mask WIN or ALT keyup events." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>#MenuMaskKey <span class="ver">[AHK_L 38+]</span></h1>

<p>Changes which key is used to mask <kbd>Win</kbd> or <kbd>Alt</kbd> keyup events.</p>

<pre class="Syntax"><span class="func">#MenuMaskKey</span> KeyName</pre>
<h2>Parameters</h2>
<dl>

  <dt>KeyName</dt>
  <dd><p>A <a href="../KeyList.htm">key name</a> or <a href="../KeyList.htm#vk">VKnn</a> sequence which specifies a non-zero virtual keycode.  Scan codes are used only in <span class="ver">[v1.1.28+]</span>, which also supports <a href="../KeyList.htm#sc">SCnnn</a> and VKnnSCnnn.</p></dd>

</dl>

<h2>Remarks</h2>
<p>The mask key is sent automatically to prevent the Start menu or the active window's menu bar from activating at unexpected times.</p>
<p>The default mask key is <kbd>Ctrl</kbd>. This directive can be used to change the mask key to a key with fewer side effects.</p>
<p>Good candidates are virtual key codes which generally have no effect, such as vkE8, which Microsoft documents as "unassigned", or vkFF, which is reserved to mean "no mapping" (a key which has no function).</p>
<p class="note"><strong>Note</strong>: Microsoft can assign an effect to an unassigned key code at any time. For example, vk07 was once undefined and safe to use, but since Windows 10 1909 it is reserved for opening the game bar.</p>
<p><span class="ver">[v1.1.28+]:</span> Both the VK and SC can be specified, and are not required to match an existing key. Specifying <code>vk00sc000</code> will disable all automatic masking. Some values, such as zero VK with non-zero SC, may fail to suppress the Start menu.</p>
<p>This setting is global, meaning that it needs to be specified only once (anywhere in the script) to affect the behavior of the entire script.</p>
<p><strong>Hotkeys:</strong> If a hotkey is implemented using the keyboard hook or mouse hook, the final keypress may be invisible to the active window and the system. If the system was to detect <em>only</em> a <kbd>Win</kbd> or <kbd>Alt</kbd> keydown and keyup with no intervening keypress, it would usually activate a menu. To prevent this, the keyboard or mouse hook may automatically send the mask key.</p>
<p><span class="ver">[v1.1.27+]:</span> Pressing a hook hotkey causes the next <kbd>Alt</kbd> or <kbd>Win</kbd> keyup to be masked if all of the following conditions are met:</p>
<ul>
  <li>The hotkey is suppressed (it lacks the <a href="../Hotkeys.htm#Tilde">tilde modifier</a>).</li>
  <li><kbd>Alt</kbd> or <kbd>Win</kbd> is logically down when the hotkey is pressed.</li>
  <li>The modifier is physically down or the hotkey requires the modifier to activate. For example, <code>$#a::</code> in combination with <code>AppsKey::RWin</code> causes masking when <kbd>Menu</kbd>+<kbd>A</kbd> is pressed, but <kbd>Menu</kbd> on its own is able to open the Start Menu.</li>
  <li><kbd>Alt</kbd> is not masked if <kbd>Ctrl</kbd> was down when the hotkey was pressed, since <kbd>Ctrl</kbd>+<kbd>Alt</kbd> does not activate the menu bar.</li>
  <li><kbd>Win</kbd> is not masked if the most recent <kbd>Win</kbd> keydown was modified with <kbd>Ctrl</kbd>, <kbd>Shift</kbd> or <kbd>Alt</kbd>, since the Start Menu does not normally activate in those cases. However, key-repeat occurs even for the <kbd>Win</kbd> key if it was the last key physically pressed, so it can be hard to predict <em>when</em> the most recent <kbd>Win</kbd> keydown was.</li>
  <li>Either the keyboard hook is not installed (i.e. for a mouse hotkey), or there have been no other (unsuppressed) keydown or keyup events since the last <kbd>Alt</kbd> or <kbd>Win</kbd> keydown. Note that key-repeat occurs even for modifier keys and even after sending other keys, but only for the last physically pressed key.</li>
</ul>
<p>Mouse hotkeys may send the mask key immediately if the keyboard hook is not installed.</p>
<p>Hotkeys with the <a href="../Hotkeys.htm#Tilde">tilde modifier</a> are not intended to block the native function of the key, so in <span class="ver">[v1.1.27+]</span> they do not cause masking. Hotkeys like <code>~#a::</code> still suppress the menu, since the system detects that <kbd>Win</kbd> has been used in combination with another key. However, mouse hotkeys and the <kbd>Win</kbd> keys themselves (<code>~LWin::</code> and <code>~RWin::</code>) do not suppress the Start Menu.</p>
<p>The Start Menu (or the active window's menu bar) can be suppressed by sending any keystroke. The following example disables the ability for the left <kbd>Win</kbd> key to activate the Start Menu, while still allowing its use as a modifier:</p>
<pre>~LWin::Send {Blind}{vkE8}</pre>
<p><strong>Send:</strong> <a href="Send.htm">Send</a>, <a href="ControlSend.htm">ControlSend</a> and related often release modifier keys as part of their normal operation. For example, the hotkey <code>&lt;#a::SendRaw %Address%</code> usually must release the left <kbd>Win</kbd> key prior to sending the contents of <em>Address</em>, and press the left <kbd>Win</kbd> key back down afterward (so that other <kbd>Win</kbd> key combinations continue working). The mask key may be sent in such cases to prevent a <kbd>Win</kbd> or <kbd>Alt</kbd> keyup from activating a menu.</p>

<h2>Related</h2>
<p>See <a href="https://www.autohotkey.com/board/topic/20619-extraneous-control-key-presses-generated-by-or-hotkeys/">this thread</a> for background information.</p>

<h2>Examples</h2>
<div class="ex" id="ExBasic">
<p><a href="#ExBasic">#1</a>: Basic usage</p>
<pre>#MenuMaskKey vkE8  <em>; Change the masking key to something unassigned such as vkE8.</em>
#Space::Run % A_ScriptDir  <em>; An additional Ctrl keystroke is not triggered.</em></pre>
</div>

<div class="ex" id="ExAdvanced">
<p><a href="#ExAdvanced">#2</a>: Shows in detail how this directive causes vkFF to be sent instead of LControl.</p>
<pre>#MenuMaskKey vkFF  <em>; vkFF is no mapping.</em>
#UseHook
#Space::
!Space::
    KeyWait LWin
    KeyWait RWin
    KeyWait Alt
    KeyHistory
return</pre>
</div>

</body>
</html>
